…sandbox hardening

Wholesale restructure now that v0.3.2 is shipped. Goals:
- audience routing from README so eval researchers / task authors / agent
  builders / Harbor migrators land on the right page
- pin the mental model in one place (Trial / Scene / Role / Verifier +
  full lifecycle diagram) instead of scattering it across api-reference
  and use-cases
- promote the SWE-bench Pro / Josh @ GitHub progressive-disclosure case
  study to a first-class section in progressive-disclosure.md, with
  Harbor #1316 parity comparison and the soft-verify vs full-verify split
- give sandbox hardening its own page and route to labs/ for the
  empirical validation

## Structure

  README.md                          — audience routing, doc map, featured + research
  CLAUDE.md                          — minimal: setup, conventions, release shape
  docs/getting-started.md            — was quickstart.md, slim, links forward
  docs/concepts.md                   — NEW: primitives, lifecycle, multi-turn vs round vs scene
  docs/progressive-disclosure.md     — REWRITE: Josh case study, lifecycle integration,
                                        soft- vs full-verify, Harbor #1316 parity table
  docs/sandbox-hardening.md          — NEW: threat model, hardening sequence, labs index
  docs/task-authoring.md             — unchanged (already solid)
  docs/use-cases.md                  — unchanged (multi-agent patterns)
  docs/skill-eval.md                 — was skill-eval-guide.md (rename only)
  docs/examples/                     — was docs/notebooks/ (rename only)
  docs/reference/cli.md              — was docs/cli-reference.md
  docs/reference/python-api.md       — was docs/api-reference.md

labs/ stays at repo root — runnable research code with relative imports;
referenced from docs/sandbox-hardening.md and README "Research artifacts."

## What's new content-wise

- docs/concepts.md (new): the five primitives (Task / Agent / Environment /
  Verifier / Trial), trial lifecycle ASCII diagram, Scenes/Roles/Turns,
  User abstraction summary, multi-turn vs multi-round vs multi-scene table.
- docs/progressive-disclosure.md (rewrite): full SWE-bench Pro case study
  with the 2026-04-24 Daytona validation table, lifecycle integration
  diagram showing where _run_user_loop plugs in, soft-verify vs full-verify
  comparison, Harbor #1316 parity discussion, expanded API reference.
- docs/sandbox-hardening.md (new): the BenchJack/Meerkat threat context,
  the 10-step hardening sequence, the per-task [verifier.hardening]
  opt-out semantics, and labs/ as empirical validation.
- README.md: PyPI badge 0.3.0a3 → 0.3.2, audience routing table,
  documentation index, featured progressive-disclosure callout, research
  artifacts section linking labs.
- CLAUDE.md: trimmed to the essential conventions (test discipline,
  human review, trunk-based, release shape).

Cross-references updated throughout (no broken links to old paths).

…re data

- Removed all "Josh @ GitHub/Microsoft" / "Josh's" references from docs,
  README, example script, and notebook. Reframed as "the SWE-bench Pro
  progressive-disclosure use case" with Harbor #1316 as the cited PR.

- Ran progressive disclosure (3 rounds, Gemini 3.1 Pro Preview, Daytona)
  on all 5 oracle-passing SWE-bench Pro tasks. Results aggregated to
  experiments/swebench-pro-progressive-results.json and rendered into
  the notebook + docs:
    ansible      error: stdout closed at 17min
    flipt        0.0 (195 tools, 3 rounds)
    openlibrary  1.0 (82 tools, 3 rounds — soft 0.0 each, final 1.0)
    navidrome    0.0 (145 tools, 3 rounds)
    qutebrowser  error: agent timeout at 50min

  Honest take in the docs: infrastructure works, two infra failures
  unrelated to disclosure, no measurable lift on flipt with this model
  on this run. Single-model run, not a paper comparison.

- Fixed AttributeError in swebench_pro_user_dogfood.py (RunResult has
  no trial_dir attribute) — script was crashing post-trial.

After the 'agent_idle_timeout + EOF diagnostics' fix, re-ran ansible
and qutebrowser (the two that flaked on first attempt). Both completed
3 rounds and reached final reward 1.0.

Final 5-task results (Gemini 3.1 Pro, Daytona, 3 rounds each):

  Task         Final  Tools  Rounds soft-verify   Notes
  ansible      1.0    126    0.0 / 0.0 / 0.0      passed on retry (1st: stdout EOF)
  flipt        0.0    195    0.0 / 0.0 / 0.0      hard fail
  openlibrary  1.0    82     0.0 / 0.0 / 0.0      baseline already passed
  navidrome    0.0    145    0.0 / 0.0 / 0.0      hard fail
  qutebrowser  1.0    183    0.0 / 0.0 / 0.0      passed on retry (1st: 50min timeout)

3/5 final pass. flipt and navidrome stayed at 0.0 across all rounds —
Gemini 3.1 Pro doesn't crack them with this hint schedule.

Updated:
- experiments/swebench-pro-progressive-results.json
- examples/swebench_pro_progressive_disclosure.ipynb (re-executed with new data)
- docs/progressive-disclosure.md validation table + commentary

Three findings, all real:

1. docs/reference/python-api.md:230 — relative link broken after the
   docs/api-reference.md → docs/reference/python-api.md move. Fix: use
   ../examples/ instead of docs/examples/.

2. _acp_run.py _prompt_with_idle_watchdog — race condition: after
   `await asyncio.sleep(poll_interval)`, prompt_task could have
   completed during the sleep. Without re-checking `done()` before the
   timeout evaluations, we'd cancel a completed task and silently
   discard a successful result. Added a `done()` re-check that breaks
   out of the loop.

3. trial.py:674 — the TimeoutError handler was overwriting the idle
   watchdog's detailed message ("Agent idle for 600s with no new tool
   call (last activity 642s ago, 0 tool calls so far)") with a generic
   "Agent timed out after {self._timeout}s" using the wall-clock
   budget, not the idle timeout. Preserve the watchdog's message when
   present; fall back to the generic message only when the exception
   has no detail.

Devin caught: _prompt_with_idle_watchdog created prompt_task with
asyncio.create_task() but only cancelled it on the explicit timeout
branches. If the parent coroutine was cancelled externally
(asyncio.timeout, task.cancel(), Ctrl+C), CancelledError propagated
out of the sleep without cancelling prompt_task — leaking the agent
prompt until Trial.cleanup() eventually killed the process, plus
asyncio's "Task exception was never retrieved" warning.

Wrap the polling loop in try/finally so cancel + drain always runs,
including the implicit-cancellation path. Both timeout branches now
just `raise TimeoutError(...)` without their own cancel/drain block —
the finally handles it uniformly.

Devin caught: the execute_prompts docstring says idle_timeout fires
when "no tool call OR message arrives", but _prompt_with_idle_watchdog
was only polling session.tool_calls. ACPSession also accumulates
message_chunks and thought_chunks via handle_update — agents actively
streaming text without producing a new tool call would be falsely
aborted.

Use a single _activity_count() that sums tool_calls + message_chunks +
thought_chunks so any of the three resets the idle timer. Updated the
TimeoutError message to mention all three categories.

Devin caught: poll_interval was computed solely from idle_timeout
(min(30, max(5, idle_timeout // 4))). With the default idle_timeout=600,
poll_interval was always 30s. The wall-clock deadline was only checked
after each `await asyncio.sleep(poll_interval)`, so a task with
timeout_sec=60 could overshoot to 90s (50%); timeout_sec=30 could
overshoot to 60s (100%).

Pre-PR, execute_prompts used asyncio.wait_for() which enforced the
wall-clock timeout precisely. Adding the idle watchdog as the new
default path silently regressed timeout precision.

Fix: factor timeout into the poll interval too — `min(30, idle_timeout
// 4, max(1, timeout // 4))` floored at 1. Short total budgets now get
proportionally shorter poll intervals.